docs(skills): publish skills from a docs.yml path and deprecate repository - #5905
Open
matlegault wants to merge 5 commits into
Open
docs(skills): publish skills from a docs.yml path and deprecate repository#5905matlegault wants to merge 5 commits into
matlegault wants to merge 5 commits into
Conversation
… path The skills config rework in fern-api/fern#16510 removes the `repository` display field from page-actions.options.skills (the schema becomes strict) and adds a `path` field that points the CLI at a directory of skills in the docs repo, which it validates, bundles, and publishes. - fern/docs.yml: drop the repository line; keep title/description/learn-more-url, the manual skills array, and install-command (npx skills add fern-api/skills) - host-skills.mdx: rework to recommend declaring page-actions.options.skills.path; demote the hand-built .well-known/skills/ convention to a legacy fallback - install-skills-properties.mdx: add the path ParamField, remove repository - site-level-settings.mdx: path-based Install skills example, drop repository Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
|
||
| <Markdown src="/products/docs/snippets/install-skills-properties.mdx" /> | ||
|
|
||
| ## Legacy: hand-built `.well-known/skills/` |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Headings] 'Legacy: hand-built *******************' should use sentence-style capitalization.
|
|
||
| <Markdown src="/products/docs/snippets/install-skills-properties.mdx" /> | ||
|
|
||
| ## Legacy: hand-built `.well-known/skills/` |
Contributor
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.HeadingColons] Capitalize ': h'.
| </ParamField> | ||
|
|
||
| <ParamField path="page-actions.options.skills.path" type="string" required={false} toc={true}> | ||
| Path to a directory of agent skills in this repo. Resolved relative to the folder containing `docs.yml`; `../` is allowed (e.g. a repo-root `.agents/skills/` directory that also serves local coding agents). Every subdirectory containing a `SKILL.md` is published as one skill: the CLI validates the bundle, generates the `/.well-known/skills/index.json` discovery manifest, and uploads every file so that `npx skills add https://<your-docs-domain>` works. Nothing is written back to your repo. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'SKILL' has no definition.
Contributor
|
🌿 Preview your docs: https://fern-preview-matlegault-skills-path-config-docs.docs.buildwithfern.com/learn Here are the markdown pages you've updated: |
devalog
approved these changes
Jun 22, 2026
Co-Authored-By: Claude <noreply@anthropic.com>
matlegault
marked this pull request as ready for review
July 13, 2026 18:42
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
fern#16510 no longer removes `page-actions.options.skills.repository` — a later commit re-added it as deprecated-and-ignored so existing docs.yml files keep loading. Document it that way instead of dropping it. The modal's generated install command is built from the bare host (fern-platform resolves `useParams().domain`, which carries no basepath), so our /learn basepath is dropped and the command would probe the root domain. Set `install-command` explicitly and note the caveat wherever the default is documented. Also refresh the modal description now that the skill ships from this repo rather than fern-api/skills, and add a migration note for hand-built .well-known bundles. Co-Authored-By: Claude <noreply@anthropic.com>
matlegault
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Blocked on fern-api/fern#16510 — keep as draft until it merges and ships in a release.
That PR adds
page-actions.options.skills.path: the CLI discovers a same-repo skills directory, validates the bundle, generates the.well-known/skills/index.jsonmanifest, and publishes it atfern generate --docs, with nothing written back to the repo. It also deprecatespage-actions.options.skills.repository— the field is still accepted so existingdocs.ymlfiles keep loading, but the CLI no longer forwards it, so the modal stops rendering a "View source" button.#16510 is still open and unreleased (its changelog sits in
changes/unreleased/feat-skills-declared-path.yml), so the Preview Docs check here fails withInvalid object at path $.page-actions.options.skillsuntil it lands.Changes
fern/docs.yml— declarepath: ../.agents/skillsand drop the hand-listedskills:array andrepository:.install-commandis set explicitly tonpx skills add https://buildwithfern.com/learn: the generated default is built from the bare host, so it would drop our/learnbasepath and probe the root domain, which isn't served by the docs app..agents/skills/fern-docs/— vendor thefern-docsskill (currently identical tofern-api/skills@main) so it publishes from this site and doubles as the local coding-agent skill.host-skills.mdx— reworked around declaringpath: resolution rules (../allowed, e.g. a repo-root.agents/skills/), what the CLI validates, where the manifest and skills are served, and the basepath caveat on the install command. Adds a note for anyone hand-maintainingfern/.well-known/skills/orfern/.well-known/agent-skills/— that passthrough still works when nopathis set, and a declaredpathwins.install-skills-properties.mdx— added thepathParamField;repositoryis documented as deprecated and ignored rather than removed.site-level-settings.mdx— "Install skills action" example now usespath.Remaining steps at release
fern/fern.config.jsononmain(5.59.0 today) is at or past the release containingfeat-skills-declared-path.Known gap (not fixed here)
The modal's default install command drops the docs basepath for every hosted site, not just ours —
PageActions.tsxresolvesuseParams().domainto the bare host and only appends a self-hosted basepath. The explicitinstall-commandabove works around it forbuildwithfern.com/learn; customers on a basepath who adoptpathwill hit the same thing until fern-platform is fixed.🤖 Generated with Claude Code